Skip to main content

External EMR Search Feature Implementation Guide

Overview​

This document provides implementation guidance for adding external EMR patient search functionality to the BookAppointment.tsx component. The feature will enable clinic staff to search for and select a single patient (either from internal database or external EMR) to book an appointment on their behalf. The implementation leverages the existing EmrInterface with getPatient implementations for dynamic EMR integration.

Use Case: Single Patient Selection for Appointment Booking​

Workflow Overview​

  1. Staff initiates search: Clinic staff begins typing patient information (name, email, phone)
  2. Unified search results: System searches both internal database and external EMR simultaneously
  3. Patient selection: Staff selects one specific patient from the search results
  4. Appointment creation: Selected patient information is used to create the appointment
  5. Clear visual feedback: Selected patient is prominently displayed with option to change selection

Proposed External EMR Search Architecture​

1. EMR Interface Structure​

Each EMR system implements a standardized EmrInterface with a getPatient method that accepts search parameters and returns patient data in a consistent format. External patients are distinguished from internal patients with source indicators and EMR system identifiers.

2. Dynamic EMR Resolution Service​

An EMR resolver service automatically determines which EMR system each clinic uses and routes search requests to the appropriate EMR implementation. This service integrates with existing business location configuration to fetch EMR credentials and connection details.

3. Enhanced Patient Search Service​

The existing PatientApi service is extended with new endpoints:

  • searchExternalPatients: Searches only external EMR patients for the clinic
  • searchAllPatients: Searches both internal and external patients, merging results

These endpoints integrate with the EMR resolver service to automatically query the appropriate EMR system for each clinic.

4. Backend API Implementation​

New backend endpoints handle the EMR integration:

  • External Patient Search: Resolves clinic's EMR system, calls the appropriate getPatient method, and returns standardized patient data
  • Combined Search: Searches both internal and external sources, merges results, handles deduplication, and returns unified results with source indicators

5. Enhanced BookAppointment Component​

The BookAppointment.tsx component is enhanced to support single patient selection from unified search results:

Key Changes:

  • Unified Search: Combines internal and external patient search with a single interface
  • Patient Selection State: Maintains selected patient state for appointment booking
  • Search Mode Options: Allows switching between internal-only, external-only, or combined search
  • Clear Selection: Provides ability to clear selected patient and search again
  • Visual Feedback: Shows selected patient prominently with source identification

6. User Interface Components​

Search Mode Toggle: Radio buttons allowing staff to choose between searching all patients, internal patients only, or external EMR patients only.

Patient Search Results: Displays unified search results with clear visual indicators showing whether each patient is from the internal database or external EMR system.

Selected Patient Display: Once a patient is selected, prominently displays their information with the ability to clear the selection and search again.

Source Identification: Clear badges and visual cues distinguish between internal and external patients, showing the specific EMR system for external patients.

Implementation Steps​

Phase 1: Backend Foundation​

  1. EMR Configuration Management

    • Add EMR configuration fields to business location model
    • Create API endpoints for EMR configuration management
    • Implement EMR resolver service

  2. External Search API

    • Implement external patient search endpoint
    • Implement unified patient search endpoint
    • Add proper error handling and timeout management

Phase 2: Frontend Integration​

  1. Service Layer Updates

    • Extend PatientApi with external search endpoints
    • Add proper TypeScript types for external patients

  2. Component Enhancement

    • Update BookAppointment.tsx with unified search and single patient selection
    • Add search mode toggle UI
    • Implement selected patient display with clear selection option
    • Enhance patient result display with source indicators

Phase 3: Testing & Optimization​

  1. Testing

    • Unit tests for EMR resolver service
    • Integration tests for external search

  2. Performance Optimization

    • Implement result caching
    • Add pagination for external results
    • Optimize search debouncing
    • Ensure smooth patient selection and appointment creation flow

Environment Variables​

System-level configuration for EMR integration timeouts, caching policies, and result limits to ensure optimal performance and reliability.

Error Handling​

External EMR Failures​

  • Gracefully degrade to internal search only
  • Display appropriate error messages to users
  • Log EMR connection issues for monitoring

Rate Limiting​

  • Implement rate limiting for EMR API calls
  • Cache frequent searches to reduce EMR load
  • Provide fallback mechanisms

Metrics to Track​

  • External search success/failure rates
  • EMR response times
  • Search result relevance
  • User adoption of external search